This document does not cover adding help to vtcl applications, although the same document architecture applies.
This should not be confused with the http server which is responsible for sending HTML documents to the scohelp (or mosaic) clients. The http server will be documented as part of the scohelp functional specification.
Although using hard-coded topic names is fairly simple conceptually, there are some definite disadvantages to this approach:
All of these methods result in a request being sent to the help server indicating which help book and topic should be displayed. While this request is being sent, a wait cursor should be displayed to provide the user with visual feedback. General descriptions of the behaviour the user should see in various situations are provided in the following sections.
Note that a given client may support any, all, or none of the above methods. Any deviations from the functionality described here should ideally be documented in the functional specification for the client in question (at least in the case of clients actively supported by SCO). Also, the behaviour described here is dependent on the online documentation provided. If the online documentation is incorrect or incomplete then help will not work correctly.
The technical details about what the developer and author actually need to do to make this behaviour occur are provided in the sections below, "Adding Help to an X Client" and "Authoring Help Files".
If the user makes a selection outside of the client window (or in the window border) an error message is displayed indicating that help must be requested from within the application.
None of the Help menu items described above are required, it is up to the client developer to decide which options are appropriate for each client, and create the specified user interface in a manner consistent with other X clients.
The process command ps(C) will show that one of the command line arguments to the scohelp process is "-cshelpservermode" when it is in server mode.
Selecting "Close Window" from the scohelp client will only close that particular help window. If the window that was closed was a primary help window for a client then subsequent help requests from that client will create a new primary help window, either by using one of the other windows associated with the client or by creating a new window if no others exist.
It is important to note that closing the last visible help window will not actually cause the scohelp client to exit. Scohelp will only exit when the last client connected exits.
When the help server receives a request to open a hard-coded topic name it checks to see if an entry containing the hard-coded topic name exists in the hook file. If one does exist, it attempts to open the topic that it maps to, otherwise it will attempt to open the original topic directly.
Most SCO clients use widget tree sums instead of the hard-coded topic names, but this scheme is for internal SCO use only, and is not supported in this API, except that the sums are communicated to the help server.
This feature of Motif means that the helpCallback only needs to be added to certain key widgets. For example, a helpCallback could be added to the parent of the set of widgets for which you wanted to provide a common help topic.
The three functions provided by this api are:
HelpStatus HelpOpen() Initalize data structures for communicating with server HelpStatus HelpDisplay() Sends requests to the help server HelpStatus HelpClose() Closes the help connection
#include </usr/skunk/include/scohelp/api.h>
HelpStatus HelpOpen(client_context, toplevel, bookdir,
wait_cursor, error_handler)
XtPointer *client_context;
Widget toplevel;
char *bookdir;
void ((*wait_cursor)(Boolean));
void ((*error_handler)(char *));
HelpOpen()
performs the initialization necessary for communicating with the help server.
It returns helpSuccess on success and helpCreateClientFailure
if the initialization fails.
Upon successful return from this function, the address specified by client_context will point to an allocated and initialized structure containing information about the client. The pointer to this structure is used in subsequent calls to HelpDisplay() and HelpClose(). The memory allocated for this structure is automatically free'd when HelpClose() is called by the client. Note that client_context and the structure that it points to should not be modified by the client.
toplevel is the widget id of the calling application's toplevel widget (after Xt initalization). NOTE: In earlier versions of the api it was required that this widget be an always present, realized widget. This is no longer required.
bookdir is the name of the default book used by the client (eg., XDeskHelp). This value can be overriden in subsequent calls to HelpDisplay() if the client needs to open multiple books. Ibookdir is assumed to be the name of a valid help book, no checking is done by this routine. The client's default help book should ideally be specified via a resource named "helpBook" so that there is a consistent way of specifying books across the clients.
The name specified by bookdir is actually the name of a subdirectory where the topics contained in the client's help book reside. By default, this subdirectory resides on the clients machine in /usr/lib/scohelp (although this can be overridden via the scohelp docServer resource and/or by changing DocumentRoot on the server). For more information, see the section below, "Online Book Organization".
wait_cursor, if non-NULL, points to a function within the client that is responsible for turning the wait cursor on and off. The wait_cursor routine is called with a value of TRUE when the client should display a wait cursor (eg., when waiting for a response from the help server) and FALSE when the client should display its default cursor.
error_handler, if non-NULL, points to a function in the client responsible for displaying error messages (typically in an error dialog box). This routine will be called with a character string containing the error message that should be displayed. For example, if the help server is not installed this routine would be called with a message indicating that the help server is not available.
#include </usr/skunk/include/scohelp/api.h> HelpStatus HelpDisplay(client_context, bookdir, obj_type, entry) XtPointer client_context; char *bookdir; HelpObject obj_type; char *entry;
HelpDisplay() sends a request to the help server indicating which topic should be displayed. It would typically be called from a client's helpCallback. helpSuccess is returned upon success, otherwise it returns one of: helpBusy, helpStartupFailure, helpInvalidObject, helpSendEventFailure, or helpNoBookSpecified indicating that an error occurred while attempting to send a request.
client_context points to the data structure initialized in the call to HelpOpen(). Note that in this case the pointer to the structure is passed, not the address of the pointer.
bookdir, if non-NULL, specifies the name of the book to open. If this value is NULL, then the default book specified in the call to HelpOpen() will be used. If neither name is valid the function will return helpNoBookSpecified.
obj_type specifies what type of request is being made. Possible values for this parameter include: helpTopic for hard-coded topic names and helpWidget for widget tree names.
entry is a null-terminated string specifying the topic to be displayed. If the request is for a hard-coded topic name, as specified by the obj_type parameter, then this parameter contains the literal string representing the topic name to display. If the request is for a widget tree name, then this argument contains the full pathname of the widget for which help is desired. Widget trees are for internal SCO use only.
#include </usr/skunk/include/scohelp/api.h> HelpStatus HelpClose(client_context) XtPointer client_context;
HelpClose() should be called when the client wants to close all of its associated help windows, typically when the client exits.
client_context points to the data structure initialized in the call to HelpOpen(). The space that was allocated for this structure in HelpOpen() is free'ed by this call. Note that in this case the pointer to the structure in passed, not the address of the pointer.
HelpClose() always returns helpSuccess.
main()
{
XtPointer ClientInfo;
.
.
TopLevel = XtAppInitialize(&appContext, CLASSNAME, NULL, 0, &argc, argv,
NULL, NULL, 0);
ret = HelpOpen(&ClientInfo, TopLevel, AppData.helpBook, displayWaitCursor, errHandler);
if (ret != helpSuccess)
.
.
XtRealizeWidget(TopLevel);
.
.
}
static void
displayWaitCursor(on)
Boolean on;
{
.
.
if (on)
XDefineCursor(display, XtWindow(TopLevel), WaitCursor);
else
XUndefineCursor(display, XtWindow(TopLevel));
}
static void
errHandler(message)
char *message;
{
.
.
xm_errstr = XmStringCreateLtoR(message, XmSTRING_DEFAULT_CHARSET);
XtVaSetValues(errorDialog, XmNmessageString, xm_errstr, NULL);
XmStringFree(xm_errstr);
if (!XtIsManaged(errorDialog))
XtManageChild(errorDialog);
}
extern XtPointer ClientInfo;
.
.
ret = HelpDisplay(ClientInfo, NULL, helpTopic, "ReadingMail");
if (ret != helpSuccess)
.
.
exitClient()
{
extern XtPointer ClientInfo;
.
.
HelpClose(ClientInfo);
}
This api currently uses a property on the root window to prevent multiple invocations of the help server from occurring. Although this property is present only temporarily, if something out of the ordinary happens (ie., the client or scohelp dies before the help server comes up) this property may be left around and will prevent the help server from ever starting. If help requests are failing silently, check for this property and remove it by using the xprop command as follows:
To check for the existence of this property:
xprop -root | grep -y "lock"
To remove the property:
xprop -root -remove "_SCO_HELP_SERVER_LOCK for"
where
If you see this problem, please notify SCO.
The default location of all books is on the local machine in /usr/lib/scohelp. The docServer resource can be used to specify an alternative server. The server configuration files can set DocumentRoot to some other location besides /usr/lib/scohelp (but all the documentation must be in the same directory). The documentation can be viewed directly using scohelp in Web Browser Mode. The DocumentRoot is automatically inserted by the server. For example, using the default location of the topic "UsingTheDesktop" in the book "XDeskHelp" could be viewed by executing Open URL and specifying:
http://localhost/XDeskHelp/UsingTheDesktop.htmlon the localmachine the file can be found in
/usr/lib/scohelp/XDeskHelp/UsingTheDesktop.htmlFor more information on the documentation architecture, see the scohttp(ADM) man page.
If a hook file does exist, it must be located on the client machine and in the directory specified by the scohelp resource hookPath (by default /usr/lib/scohelp) in a subdirectory with the same name as the book, and the hookfile must have the same name as the book plus a ".hk" extension (eg., "XDeskHelp.hk").
! XDeskHelp.hk intro UsingTheDesktop icons DesktopIcons Describes icons available mouse ../GECG/UsingTheMouse Describes the scomouse client click ../GECG/UsingTheMouse Describes the scomouse client color Controls#ChangingPalettes Using scocolor paint Controls#ChangingPalettes Using scocolor A1534898 UsingTheDesktop SCO use only
Because the topic names specified in the second column are the name of actual physical files, it is possible to use relative pathnames in this field to specify topics that exist in other books. It is also possible to use the "#" syntax supported in scohelp cross references (HREF) to refer to a section in the middle of a file.
Note that only relative pathnames are supported, full pathnames should never be used in this context.